1.1 Critères d’acceptation

Afin d’assurer la cohérence de la collection et une certaine qualité du contenu des fiches Rzine, plusieurs critères d’acceptation ont été définis. Certains de ces critères peuvent faire l’objet d’un refus immédiat du comité de lecture, d’autres sont soumis à plusieurs évaluateur·rice·s.

Les éditeur·rice·s et les évaluateur·rice·s veilleront à ce que la démonstration soit contextualisée (champ disciplinaire d’application, enjeux en terme de reproductibilité…) et rigoureuse. Le code présenté se doit d’être lisible, commenté et reproductible. Les packages mobilisés doivent être brièvement décrits et leur utilisation justifiée. Enfin, les données utilisées dans le cadre de la démonstration doivent obligatoirement être sourcées, libres de droit et mises à disposition.

*Le cas échéant, le comité de lecture se réserve la possibilité de mettre en relation différents contributeur.rice.s pour leur proposer un travail collaboratif.

1.2 Format et template

Une fiche Rzine est la sortie HTML d’un fichier R Markdown construit avec R. Les packages nécessaires sont rmarkdown, knitr (pour la compilation) et rzine (pour le modèle de mise en page).

Il s’agit d’un document computationnel, alternant du texte et du code, permettant d’appliquer le paradigme de la programmation lettrée.

1.3 Soumission et évaluation

L’ensemble du processus de soumission et d’évaluation d’une fiche se déroule sur GitHub. Cela facilite la gestion de version, permet l’archivage et la transparence du processus.

Pour être soumise à évaluation, une fiche doit être déposée et déployée sur GitHub (cf. partie 5).

Dans le cas où l’ensemble des critères d’acceptations sont respectés, le comité de lecture désigne un·e éditeur·rice référent·e qui coordonnera tout le processus d’évaluation et de publication. Il propose également deux évaluateur·rice·s à l’auteur·e. Une fois le processus d’évaluation enclenché, les retours des évaluateur·rice·s et de l’éditeur·rice se feront publiquement sur GitHub (cf. partie 6).

1.4 Publication et licence d’utilisation

Le projet Rzine souhaite promouvoir les pratiques contribuant à une science plus ouverte et reproductible. C’est pour cette raison que l’ensemble des publications de la collection Rzine, ainsi que leurs codes sources, sont automatiquement mis à disposition de tou·te·s et libres de droit.

2.1 Installation du package rzine

Le package est mis à disposition sur un dépôt de l’organisation Rzine sur l’instance GitLab de la TGIR Huma-num. Pour l’installer et le charger :

# install.packages(remotes)
remotes::install_gitlab("rzine/package", host = "https://gitlab.huma-num.fr/", force = TRUE)
library(rzine)

2.2 Utiliser le template readrzine

setwd("/home/jeanne/Documents/Fiche_rzine")

rmarkdown::draft(file = "index.Rmd", 
                 template = "readrzine", 
                 package = "rzine", 
                 create_dir = FALSE, 
                 edit = FALSE)

2.3 Kniter la fiche (.html)

Pour générer la fiche en format HTML, il suffit de kniter (tricoter) le fichier index.Rmd.

Bien que cela soit invisible pour l’utilisateur, le fichier est d’abord converti en format Markdown puis en format HTML via Pandoc (logiciel libre de conversion de documents). Sur certaines versions de systèmes d’exploitation, le logiciel Pandoc n’est pas automatiquement disponible. Il est donc parfois nécessaire de l’installer.

Vous pouvez kniter le fichier index.Rmd de différentes manières :

1- En ligne de code

rmarkdown::render("index.Rmd", envir = new.env())

2- En clic-bouton (Rstudio)

3- Avec le raccourci clavier (Rstudio) :

• PC : CTRL + SHIFT + K,
  
• Mac : Command + Shift + K.

Un fichier du même nom en format HTML est alors créé à la racine de votre répertoire (index.html). Il s’agit du fichier index.Rmd mis en page à partir du modèle readrzine :

Il ne reste plus qu’à le remplir…

3.1 L’en-tête

L’en-tête d’un document R Markdown (parfois appelé YAML header) est délimité par deux lignes de trois tirets et contient des métadonnées et les éléments de style du document. Voici à quoi ressemble par exemple l’en-tête vierge du template readrzine :

---
title: "Titre fiche"
subtitle: "Sous-titre fiche"
date: "2022-01-20"
author: 
 - name: Premier Auteur.e
   affiliation: Affiliation_1, Affiliation_2
 - name: Second Auteur.e
   affiliation: Affiliation_1, Affiliation_2
image: "featured.png"   
logo: "figures/rzine.png"  
output:
  rzine::readrzine:
    highlight: kate
    number_sections: true
csl: Rzine_citation.csl
bibliography: biblio.bib
nocite: |
  @*
link-citations: true
# github: "author/repository"
# gitlab: "gitlab.huma-num.fr/author/repository"
# doi: "xx.xxx/xxxx.xxxxxxx"
# licence: "by-sa"

# Only Creative Commons Licence 
# 5 possible choices : "by-nd", "by", "by-nc-sa", "by-nc","by-sa"
---
  
  
  

3.2 Le texte balisé en markdown

Le corps d’un document R Markdown comprend deux types de contenu, que l’on peut librement alterner :

• Des blocs de texte brut mis en forme selon la syntaxe Markdown ;
  
• Des blocs de code, appelés chunks (cf. partie 3.3).

Le corps du document est constitué de texte mis en forme à l’aide de la syntaxe Markdown. Le Markdown est un langage de balisage léger et très facile à maîtriser, qui permet la mise en forme basique du texte.

Par exemple, le texte (brut) suivant :

Ceci est du texte en *italique*, **gras** ou en ***gras italique***.

Pour définir des listes à puces, utilisez les **tirets** :

- premier élément
- second élément

Vous pouvez également ajouter des [liens cliquables](https://rzine.fr/) 

Sera mis en page de la manière suivante dans le fichier HTML généré :

Ceci est du texte en italique, gras ou en gras italique.

Pour définir des listes à puces, utilisez les tirets :

• premier élément
• second élément

Vous pouvez également ajouter des liens cliquables

3.3 Les chunks

En plus du texte libre balisé en markdown, un document R Markdown peut évidemment contenir du code R.
Celui-ci doit être inclus dans des chunks délimités par la syntaxe suivante :

```{r}

x <- 37 + 12
print(x)

```

Pour insérer facilement un nouveau chunk, vous pouvez utiliser le menu Insert proposé par l’interface de développement RStudio, situé en haut à droite de l’éditeur de texte (à gauche du bouton Run) :

Vous pouvez également utiliser le raccourci clavier Ctrl + Alt + i ou Command + Option + I pour générer un chunk vide.

```{r nom_du_chunck}

```

```{r nom_du_chunck, echo = FALSE, warning = FALSE}

x <- 37 + 12
print(x)

```

3.4 Documentation de référence

Pour en savoir plus, pour se former au R Markdown et à la syntaxe markdown :

• Cookbook R Markdown, de Y. Xie, C. Dervieux & E. Riederer
• R Markdown Definitive Guide, de Y. Xie, J. J. Allaire & G. Grolemund
• R Markdown for Scientists, de Nicholas Tierney
• Introduction à R et au tidyverse, de Julien Barnier
• Travail collaboratif avec R, de Lino Galiana
• Pimp my RMD: a few tips for R Markdown, de Yan Holtz
• R for Data Science, de H. Wickham & G. Groelemund
• Guide de la syntaxe R Markdown, de Rstudio
• Guide de référence R Markdown, de Rstudio
• R Markdown Cheatsheet, de Rstudio
• Writing Reproducible Research Papers with R Markdown, de Resul Umit

4.1 Métadonnées d’en tête

Commencez par modifier l’en-tête du template readrzine (YAML header), en personnalisant le titre, le sous-titre, le nom de ou des auteur.es et les affiliations, comme par exemple :

---
title: "Analyse textuelle exploratoire"
subtitle: "Exploration d'un corpus de lettre avec le package Quanteda"
date: "2022-01-20"
author: 
 - name: Jeanne Dupont
   affiliation: UMR TEXTO, CNRS
 - name: Paul Edouard
   affiliation: Centre documentaire ED, Université de France

4.2 Le résumé

Il est obligatoire de proposer un résumé en début de publication. Ce résumé sera utilisé pour la page de présentation de la fiche (cf. exemple) sur le site rzine.fr, pour le dépôt Github du code source (cf. exemple), du DOI et le référencement sur HAL.

Ce résumé doit faire entre 250 à 800 caractères (espaces comprises). Il peut comprendre des informations sur d’éventuels prérequis pour bien comprendre le document.

Pour mettre en forme votre résumé en introduction de fiche, utilisez le symbol “>” qui permet de créer un bloc de citation qui apparaîtra sur un fond gris. Exemple :

> Ce document... xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

> **Prérequis** : xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

Le bloc de citation apparaîtra comme suit :

Ce document… xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

Prérequis : xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

4.3 Contextualisation

Il est essentiel et obligatoire d’introduire et de contextualiser le contenu de votre document.

Vous pouvez pour cela vous appuyer sur des références bibliographiques, utiles pour les non-spécialistes de la thématique ou de la méthode présentée (cf. partie 4.10).

4.4 Données utilisées

<br/>

<p class="center">[<span style="font-size: 230%;" class="glyphicon glyphicon-download-alt"></span><br/>Télécharger les données](https://rzine.fr/docs/...../data.zip)</p>

<br/>

4.5 Packages et fonctions

Comme pour les données, il est important de consacrer un sous-chapitre aux packages utilisés. Tous les packages mobilisés pour l’analyse doivent être listés et décrits (cf. exemple) :
- package1 : description…
- package2 : description…
- package3 : description…

Tous les packages et fonctions explicitement nommés doivent également être mis en page de cette façon :

`packages` et `fonction()`

Voici le rendu : packages et fonction()

4.6 Illustration

<figure class="center">
  <img src="figures/rzine.png" width="200">
  
  <figcaption style="font-size:13px;">Logo de la collection Rzine, 2021,  [https://rzine.fr/collection/#collection](https://rzine.fr/collection/#collection){target="_blank"}</figcaption>

</figure>

4.7 Ecriture de code R

Le code R présenté dans la fiche doit être indenté, espacé et commenté. Il est demandé aux auteur·e·s de prendre soin de la syntaxe et de respecter les principales conventions d’écriture.

Pour en savoir plus, vous pouvez consulter The tidyverse style guide d’Hadley Wickham.

4.8 Message d’alerte

Il est possible d’utiliser certains messages d’alerte boostrap :

• Encadré vert (success) : pour mettre en avant une information
  
• Encadré rouge (danger) : our mettre en relief une information primordiale

La syntaxe HTML à utiliser est :

<div class="alert alert-success" role="alert">Message d'information</div>

**ET**
 
<div class="alert alert-danger" role="alert">Message <b>très important</b></div>

Voici le rendu :

ET

4.9 Formules mathématiques

Il est possible d’écrire des formules mathématiques en langage \(\TeX\). Il suffit de délimiter le contenu \(\LaTeX\) par un ou deux symboles $, ex :

$$ y = \sqrt{\frac{1}{x + \beta}} $$ 

En mode Inline (un seul $) , les formules sont incluses à l’intérieur du paragraphe courant, ex : \(\sum_{i=1}^n X_i\)
En mode Displayed (deux $), elles apparaissent centrées et mises en exergue, ex : \[ y = \sqrt{\frac{1}{x + \beta}} \]

4.10 Références bibliographiques

Le template readrzine intègre automatiquement une section de références bibliographiques. Il est fortement recommandé aux auteur·e·s de l’utiliser. Cependant cette section n’est pas obligatoire, vous pouvez supprimer les lignes suivantes dans le fichier index.rmd si vous ne souhaitez pas afficher de bibliographie :

# Bibliographie {-}

<div id="refs"></div>

Sinon, pour ajouter des références bibliographiques, complétez le fichier biblio.bib.

Trois références bibliographiques sont saisies par défaut dans le fichier biblio.bib :

@Manual{R-base,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2020},
  url = {https://www.R-project.org/},
}

@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
  author = {Yihui Xie},
  year = {2020},
  note = {R package version 1.28},
  url = {https://CRAN.R-project.org/package=knitr},
}

@Manual{R-rmdformats,
  title = {rmdformats: HTML Output Formats and Templates for 'rmarkdown' Documents},
  author = {Julien Barnier},
  year = {2021},
  note = {R package version 1.0.2},
  url = {https://github.com/juba/rmdformats},
}

Beaucoup de documentation sur les fichiers BibTex sont consultables sur internet (exemple). Supprimez et ajoutez les références bibliographiques que vous souhaitez.

4.11 Glossaire

Cette section n’est pas obligatoire, cependant vos lecteur.rices ne seront pas forcément issu·es de votre discipline ou ne maîtriseront peut-être pas la thématique ou méthode présentée. En définissant certains termes utilisés, la section « Glossaire » permet de rendre la démonstration compréhensible à un public plus large.

Pour ajouter un mot ou expression, ainsi que sa définition dans le Glossaire, utilisez la syntaxe markdown suivante :

texte texte texte mot à définir^[__Mot à définir__: Définition du terme... ]

A la compilation du document en format HTML, un numéro est automatiquement associé et affiché après le “mot à définir”. Ce mot/expression et sa définition sont ajoutés dans la section « Glossaire ». Exemple : Mot à définir¹

Si vous ne souhaitez pas utiliser de Glossaire, supprimez les lignes suivantes dans le fichier index.rmd :

## Glossaire {- #endnotes}

```{js, echo=FALSE}

$(document).ready(function() {
  $('.footnotes ol').appendTo('#endnotes');
  $('.footnotes').remove();
});

```


<br/>

4.12 Informations sur la session

Cette section obligatoire est directement intégrée au template.

## Info session  {-}

```{r session_info, echo=FALSE}
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[1]], row.names = F))
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[2]], row.names = F))
```

Ce bout de code affiche des informations sur la session qui a permis de générer la fiche (système d’exploitation, versions de R et des packages utilisés). Voir l’exemple pour ce document.

4.13 Citation BibTex

Cette section obligatoire est directement intégrée au template.

## Citation {-}

```{r Citation, echo=FALSE}

rref <- bibentry(
   bibtype = "article",
   title = "Titre de la fiche",
   author = person("Auteur.e 1", "Auteur.e 2" ),
   journal = "Rzine.fr",
   publisher = "FR CIST",
   year = 2021,
   url = "https://...")

``` 

`r capture.output(print(rref))`

### BibTex : {-}

```{r generateBibTex, echo=FALSE}

writeLines(toBibtex(rref), "cite.bib")
toBibtex(rref)

``` 


<br/>

Ne mofifiez pas cette section, elle sera complétée avant publication par l’équipe éditoriale. Ces deux chunks permettent l’affichage de la référence bibliographique de votre fiche dans le corps du document (Voir l’exemple pour ce document), ainsi que le stockage de cette référence en format BibTex, enregistrée dans le fichier cite.bib à la racine du répertoire.

5.1 Premiers pas sur Github

Le logiciel de gestion de versions décentralisé que vous devez utiliser pour la soumission est GitHub.

5.2 Remplissage du dépôt

Vous pouvez désormais y ajouter le répertoire (et sous-répertoires) contenant tous les fichiers de votre fiche. Il existe plusieurs méthodes pour téléverser des fichiers sur GitHub (en ligne de commande ou en clic-bouton). Nous présentons ici la méthode clic-bouton depuis l’interface de GitHub.

Cliquez sur “Add file”, puis sur “Upload files” :.

Ajoutez un commentaire et cliquez sur “Commit changes” :

Vous venez de réaliser votre premier “commit” (enregistrement des changements). L’ensemble des fichiers est désormais stocké sur le dépôt :

Ce dépôt étant paramétré comme public, tout le monde peut désormais le consulter et récupérer les fichiers qu’il contient.

5.3 Déploiement de la fiche

Les fichiers sont consultables à l’état brut, mais une manipulation supplémentaire va permettre de mettre en ligne votre fiche (format HTML). Votre fiche mise en forme sera ainsi consultable par tout le monde sur le web, sans avoir à gérer un serveur ou un site web.

5.4 Soumettre

Il ne vous reste plus qu’à contacter le comité de lecture Rzine pour soumettre votre fiche pour évaluation. Envoyez un courriel à collection[a]rzine.fr, en précisant l’adresse du dépôt qui héberge votre fiche.

Vous serez contacté·e par le comité de lecture dans les 15 jours suivants l’envoi de ce courriel.